home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / man3 / CrtSelHdlr.3 < prev    next >
Text File  |  1994-09-20  |  10KB  |  317 lines
  1. '\"
  2. '\" Copyright (c) 1990-1992 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/wish/man/RCS/CrtSelHdlr.3,v 1.7 93/04/01 09:41:16 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .\" The definitions below are for supplemental macros used in Tcl/Tk
  24. .\" manual entries.
  25. .\"
  26. .\" .HS name section [date [version]]
  27. .\"    Replacement for .TH in other man pages.  See below for valid
  28. .\"    section names.
  29. .\"
  30. .\" .AP type name in/out [indent]
  31. .\"    Start paragraph describing an argument to a library procedure.
  32. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  33. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  34. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  35. .\"    needed;  use .AS below instead)
  36. .\"
  37. .\" .AS [type [name]]
  38. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  39. .\"    name are examples of largest possible arguments that will be passed
  40. .\"    to .AP later.  If args are omitted, default tab stops are used.
  41. .\"
  42. .\" .BS
  43. .\"    Start box enclosure.  From here until next .BE, everything will be
  44. .\"    enclosed in one large box.
  45. .\"
  46. .\" .BE
  47. .\"    End of box enclosure.
  48. .\"
  49. .\" .VS
  50. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  51. .\"    of man pages.
  52. .\"
  53. .\" .VE
  54. .\"    End of vertical sidebar.
  55. .\"
  56. .\" .DS
  57. .\"    Begin an indented unfilled display.
  58. .\"
  59. .\" .DE
  60. .\"    End of indented unfilled display.
  61. .\"
  62. '\"    # Heading for Tcl/Tk man pages
  63. .de HS
  64. .ds ^3 \\0
  65. .if !"\\$3"" .ds ^3 \\$3
  66. .if '\\$2'cmds'       .TH \\$1 1 \\*(^3 \\$4
  67. .if '\\$2'lib'        .TH \\$1 3 \\*(^3 \\$4
  68. .if '\\$2'tcl'        .TH \\$1 n \\*(^3 Tcl "Tcl Built-In Commands"
  69. .if '\\$2'tk'         .TH \\$1 n \\*(^3 Tk "Tk Commands"
  70. .if '\\$2'tclc'        .TH \\$1 3 \\*(^3 Tcl "Tcl Library Procedures"
  71. .if '\\$2'tkc'         .TH \\$1 3 \\*(^3 Tk "Tk Library Procedures"
  72. .if '\\$2'tclcmds'         .TH \\$1 1 \\*(^3 Tk "Tcl Applications"
  73. .if '\\$2'tkcmds'         .TH \\$1 1 \\*(^3 Tk "Tk Applications"
  74. .if t .wh -1.3i ^B
  75. .nr ^l \\n(.l
  76. .ad b
  77. ..
  78. '\"    # Start an argument description
  79. .de AP
  80. .ie !"\\$4"" .TP \\$4
  81. .el \{\
  82. .   ie !"\\$2"" .TP \\n()Cu
  83. .   el          .TP 15
  84. .\}
  85. .ie !"\\$3"" \{\
  86. .ta \\n()Au \\n()Bu
  87. \&\\$1    \\fI\\$2\\fP    (\\$3)
  88. .\".b
  89. .\}
  90. .el \{\
  91. .br
  92. .ie !"\\$2"" \{\
  93. \&\\$1    \\fI\\$2\\fP
  94. .\}
  95. .el \{\
  96. \&\\fI\\$1\\fP
  97. .\}
  98. .\}
  99. ..
  100. '\"    # define tabbing values for .AP
  101. .de AS
  102. .nr )A 10n
  103. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  104. .nr )B \\n()Au+15n
  105. .\"
  106. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  107. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  108. ..
  109. '\"    # BS - start boxed text
  110. '\"    # ^y = starting y location
  111. '\"    # ^b = 1
  112. .de BS
  113. .br
  114. .mk ^y
  115. .nr ^b 1u
  116. .if n .nf
  117. .if n .ti 0
  118. .if n \l'\\n(.lu\(ul'
  119. .if n .fi
  120. ..
  121. '\"    # BE - end boxed text (draw box now)
  122. .de BE
  123. .nf
  124. .ti 0
  125. .mk ^t
  126. .ie n \l'\\n(^lu\(ul'
  127. .el \{\
  128. .\"    Draw four-sided box normally, but don't draw top of
  129. .\"    box if the box started on an earlier page.
  130. .ie !\\n(^b-1 \{\
  131. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  132. .\}
  133. .el \}\
  134. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  135. .\}
  136. .\}
  137. .fi
  138. .br
  139. .nr ^b 0
  140. ..
  141. '\"    # VS - start vertical sidebar
  142. '\"    # ^Y = starting y location
  143. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  144. .de VS
  145. .mk ^Y
  146. .ie n 'mc \s12\(br\s0
  147. .el .nr ^v 1u
  148. ..
  149. '\"    # VE - end of vertical sidebar
  150. .de VE
  151. .ie n 'mc
  152. .el \{\
  153. .ev 2
  154. .nf
  155. .ti 0
  156. .mk ^t
  157. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  158. .sp -1
  159. .fi
  160. .ev
  161. .\}
  162. .nr ^v 0
  163. ..
  164. '\"    # Special macro to handle page bottom:  finish off current
  165. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  166. '\"    # page bottom macro.
  167. .de ^B
  168. .ev 2
  169. 'ti 0
  170. 'nf
  171. .mk ^t
  172. .if \\n(^b \{\
  173. .\"    Draw three-sided box if this is the box's first page,
  174. .\"    draw two sides but no top otherwise.
  175. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  176. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  177. .\}
  178. .if \\n(^v \{\
  179. .nr ^x \\n(^tu+1v-\\n(^Yu
  180. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  181. .\}
  182. .bp
  183. 'fi
  184. .ev
  185. .if \\n(^b \{\
  186. .mk ^y
  187. .nr ^b 2
  188. .\}
  189. .if \\n(^v \{\
  190. .mk ^Y
  191. .\}
  192. ..
  193. '\"    # DS - begin display
  194. .de DS
  195. .RS
  196. .nf
  197. .sp
  198. ..
  199. '\"    # DE - end display
  200. .de DE
  201. .fi
  202. .RE
  203. .sp .5
  204. ..
  205. .HS Tk_CreateSelHandler tkc
  206. .BS
  207. .SH NAME
  208. Tk_CreateSelHandler, Tk_DeleteSelHandler \- arrange to handle requests for the primary selection
  209. .SH SYNOPSIS
  210. .nf
  211. \fB#include <tk.h>\fR
  212. .sp
  213. \fBTk_CreateSelHandler\fR(\fItkwin, target, proc, clientData, format\fR)
  214. .sp
  215. \fBTk_DeleteSelHandler\fR(\fItkwin, target\fR)
  216. .SH ARGUMENTS
  217. .AS Tk_SelectionProc clientData
  218. .AP Tk_Window tkwin in
  219. Window for which \fIproc\fR will provide selection information.
  220. .AP Atom target in
  221. Form in which \fIproc\fR can provide the selection (e.g. STRING
  222. or FILE_NAME).  Corresponds to \fItype\fR arguments in \fBselection\fR
  223. commands.
  224. .AP Tk_SelectionProc *proc in
  225. Procedure to invoke whenever the selection is owned by \fItkwin\fR
  226. and the selection contents are requested in the format given by
  227. \fItarget\fR.
  228. .AP ClientData clientData in
  229. Arbitrary one-word value to pass to \fIproc\fR.
  230. .AP Atom format in
  231. If the selection requestor isn't in this process, \fIformat\fR determines
  232. the representation used to transmit the selection to its
  233. requestor.
  234. .BE
  235.  
  236. .SH DESCRIPTION
  237. .PP
  238. \fBTk_CreateSelHandler\fR arranges for a particular procedure
  239. (\fIproc\fR) to be called whenever the selection is owned by
  240. \fItkwin\fR and the selection contents are requested in the
  241. form given by \fItarget\fR.  \fITarget\fR should be one of
  242. the entries defined in the left column of Table 2 of the
  243. X Inter-Client Communication Conventions Manual (ICCCM) or
  244. any other form in which an application is willing to present
  245. the selection.  The most common form is STRING.
  246. .PP
  247. \fIProc\fR should have arguments and result that match the
  248. type \fBTk_SelectionProc\fR:
  249. .nf
  250. .RS
  251. typedef int Tk_SelectionProc(
  252. .RS
  253. ClientData \fIclientData\fR,
  254. int \fIoffset\fR,
  255. char *\fIbuffer\fR,
  256. int \fImaxBytes\fR);
  257. .RE
  258. .RE
  259. .fi
  260. The \fIclientData\fP parameter to \fIproc\fR is a copy of the
  261. \fIclientData\fP argument given to \fBTk_CreateSelHandler\fR.
  262. Typically, \fIclientData\fR points to a data
  263. structure containing application-specific information that is
  264. needed to retrieve the selection.  \fIOffset\fR specifies an
  265. offset position into the selection, \fIbuffer\fR specifies a
  266. location at which to copy information about the selection, and
  267. \fImaxBytes\fR specifies the amount of space available at
  268. \fIbuffer\fR.  \fIProc\fR should place a NULL-terminated string
  269. at \fIbuffer\fR containing \fImaxBytes\fR or fewer characters
  270. (not including the terminating NULL), and it should return a
  271. count of the number of non-NULL characters stored at
  272. \fIbuffer\fR.  If the selection no longer exists (e.g. it once
  273. existed but the user deleted the range of characters containing
  274. it), then \fIproc\fR should return -1.
  275. .PP
  276. When transferring large selections, Tk will break them up into
  277. smaller pieces (typically a few thousand bytes each) for more
  278. efficient transmision.  It will do this by calling \fIproc\fR
  279. one or more times, using successively higher values of \fIoffset\fR
  280. to retrieve successive portions of the selection.  If \fIproc\fR
  281. returns a count less than \fImaxBytes\fR it means that the entire
  282. remainder of the selection has been returned.  If \fIproc\fR's return
  283. value is \fImaxBytes\fR it means there may be additional information
  284. in the selection, so Tk must make another call to \fIproc\fR to
  285. retrieve the next portion.
  286. .PP
  287. \fIProc\fR always returns selection information in the form of a
  288. character string.  However, the ICCCM allows for information to
  289. be transmitted from the selection owner to the selection requestor
  290. in any of several formats, such as a string, an array of atoms, an
  291. array of integers, etc.  The \fIformat\fR argument to
  292. \fBTk_CreateSelHandler\fR indicates what format should be used to
  293. transmit the selection to its requestor (see the middle column of
  294. Table 2 of the ICCCM for examples).  If \fIformat\fR is not
  295. STRING, then Tk will take the value returned by \fIproc\fR and divided
  296. it into fields separated by white space.  If \fIformat\fR is ATOM,
  297. then Tk will return the selection as an array of atoms, with each
  298. field in \fIproc\fR's result treated as the name of one atom.  For
  299. any other value of \fIformat\fR, Tk will return the selection as an
  300. array of 32-bit values where each field of \fIproc\fR's result is
  301. treated as a number and translated to a 32-bit value.  In any event,
  302. the \fIformat\fR atom is returned to the selection requestor along
  303. with the contents of the selection.
  304. .PP
  305. If \fBTk_CreateSelHandler\fR is called when there already exists a
  306. handler for \fItarget\fR on \fItkwin\fR, then the existing handler
  307. is replaced with a new one.
  308. .PP
  309. \fBTk_DeleteSelHandler\fR removes the handler given by \fItkwin\fR
  310. .VS
  311. and \fItarget\fR, if such a handler exists.  If there is no such
  312. handler then it has no effect.
  313. .VE
  314.  
  315. .SH KEYWORDS
  316. format, handler, selection, target
  317.